home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / program / tmtp100d.zip / MANUAL.DOS < prev    next >
Text File  |  1997-04-02  |  42KB  |  1,320 lines
  1.                    Pascal Lite Compiler for MS DOS
  2.                          [ Version 1.00 ]
  3.  
  4.                     TMT Development Corporation
  5.  
  6.  
  7.       [[[ SEARCH THIS FILE FOR 0.nn FOR THE NEW VERSION INFORMATION ]]]
  8.  
  9.  
  10. Introduction
  11. ------------
  12.  
  13. The TMT Pascal Lite compiler is a fast compiler for the Pascal language.
  14. The compiler emits 32-bit code and supports many language extensions
  15. from Borland Pascal (BP), as well as more powerful extensions.
  16.  
  17. The compiler requires at least 2Mb of free extended memory (XMS) and
  18. a floating point co-processor.
  19.  
  20.  
  21. This manual consists of the following parts:
  22.  
  23.     - introduction
  24.     - free version limitations
  25.     - compiler installation and running
  26.     - configuration file
  27.     - memory organization
  28.     - calling convention
  29.     - implemented language description:
  30.          - restriction
  31.          - extensions
  32.          - incompatibilities
  33.     - units description:
  34.          - DOS
  35.          - CRT
  36.          - USE32
  37.          - ERRCODES
  38.          - DEBUG
  39.          - STRINGS
  40.     - version 0.33 changes
  41.     - possible problems during usage
  42.     - run_time error codes
  43.  
  44.  
  45. Free Version Limitations---Getting an unrestricted Version
  46. ----------------------------------------------------------
  47.  
  48.    The free version of the PLT compiler limits the size of the executible
  49.    program code+data+heap to approximately 1.5mb. If this restriction
  50.    prevents you from implementing your application, you should obtain
  51.    a licensed copy of the compiler.
  52.  
  53.    The other advantages of ordering an unrestricted copy of the compiler
  54.    are:
  55.                 1>      IDE
  56.                 2>      Debugger
  57.                 3>      Full on-line documentation.
  58.  
  59.    The special price of the unrestricted version of the compiler
  60.    is only US$75. The distribution is electronic; if you desire your software
  61.    to be shipped by regular mail, please contact sales@tmt.com for details.
  62.  
  63.    Unrestricted license will get you the current version of the compiler
  64.    plus all updates for up to a year as they are released.
  65.  
  66.    To order your copy of PLT/Lite, send an email to sales@tmt.com
  67.    with the credit card information (VISA, MC, AMEX, DISCOVER). Alternatively,
  68.    call 1-718-268-3756 (10-5 EST) or send check or postal order to
  69.  
  70.    TMT Development Corp.
  71.    19 POPLAR AVE,
  72.    Stony Brook, NY 11790-1751
  73.  
  74.    Foreign orders: if you are paying by check, please make sure
  75.    that your check is in US dollars and drawn on a US bank.
  76.  
  77.    All postal orders: please make sure that your order specifies a contact
  78.    email account.
  79.  
  80.    PO's: we will accept PO's from qualified institutions in US and Canada.
  81.    Please verify that your PO will be accepted before issuing it.
  82.  
  83.  
  84. Compiler installation and running
  85. ---------------------------------
  86.  
  87.    The Pascal Lite distribution is contained in the tmtpldos.zip archive.
  88.    Please, read the license.doc file before the installation.
  89.  
  90.    Follow these instructions to run the installation process.
  91.  
  92.       - create the \TMTPL directory on one of the drives (we will call
  93.         it the x: drive) using the command:
  94.             x> md TMTPL
  95.  
  96.       - copy the tmtp100d.zip file into the TMTPL directory:
  97.  
  98.             x> copy  tmtp100d.zip x:\TMTPL
  99.             x> x:
  100.             x> cd \TMTPL
  101.  
  102.       - run the PKUNZIP program to decompress the tmtp100d.zip
  103.  
  104.             x:\TMTPL> pkunzip -d tmtp100d
  105.  
  106.         (the switch "-d" unpacks with subdirectories)
  107.  
  108.       - modify the PATH statement in the autoexec.bat, to include the
  109.                 x:\TMTPL\BIN
  110.          subdirectory, if you so desire.
  111.  
  112.       - goto to \TMTPL\EXAMPLES\DOS\HELLO
  113.         compile the simple test program, "HELLO.PAS", and run it:
  114.  
  115.            x:\TMTPL> plt hello
  116.            x:\TMTPL> hello
  117.  
  118.       - read the entire manual.doc file before using the compiler for
  119.         any "real" application development.
  120.  
  121.  
  122. Contents of the distribution
  123. ----------------------------
  124.  
  125.    documentation:
  126.  
  127.       manual.doc         - description of the PLT compiler
  128.       license.doc        - license agreement
  129.       readme             - this file
  130.  
  131.    executable:
  132.  
  133.      subdirectory BIN contains following files:
  134.  
  135.        plt.cfg            - compiler configuration file
  136.        dos32.exe          - the DOS32 protected mode extender
  137.        dos4gw.exe         - the DOS/4GW protected mode extender (used by
  138.                            compiler)
  139.        plt.exe            - the PLT compiler under the DOS/4GW extender
  140.        pltpmw.exe         - the PLT compiler under the PMODE extender
  141.  
  142.    standard library object modules:
  143.  
  144.      subdirectory UNITS\ contains unit obj modules files with .FPD
  145.      extensions
  146.  
  147.       arg                - commmand line parsing unit
  148.       crt                - crt unit
  149.       debug              - post-mortem dump unit and other debugging
  150.                            functions
  151.       dos.fpd            - dos unit
  152.       doscall            - low-level DOS interface
  153.       errcodes           - run-time error codes
  154.       strings            - strings unit
  155.       system             - system unit
  156.  
  157.       also in this directory contains files:
  158.           DOS32.EXE   - DOS32 extender
  159.           STUB32.EXE  - stub for DOS32 extender
  160.           PASSTUB.EXE - PMODE-based extender
  161.  
  162.    example:
  163.  
  164.      subdirectory EXAMPLE\ contains following examples for MS DOS:
  165.  
  166.        HELLO\ - example "Hello, World" program
  167.        FLAME\ - example of direct works with I/O ports and physical
  168.                 memory
  169.        VESADEMO\ - example of import and usage VESA.OBJ file from
  170.                   DOS32 libraries.
  171. +++0.33
  172.        LIN_EQ\ - example of multidimensional open arrays usage
  173. ---0.33
  174.  
  175.    supplemential files:
  176.  
  177.       DOS32\              - subdirectory that contains the DOS32
  178.                            distribution to be used by the application.
  179.  
  180.    Running the compiler:
  181.    --------------------
  182.  
  183. The compiler is invoked with the "plt" command:
  184.  
  185.   plt [switches] <main file>
  186.  
  187. where the following switches can be used:
  188.  
  189.     -m   - make modified units (default option)
  190.     -b   - build the whole program
  191.     -c   - single compilation (without linkage)
  192.  
  193. After that the suite of object files with .FPD extensions will be
  194. established in the directory with the sources, and the executable file
  195. will be created in the current directory (if the switch -c is not set).
  196.  
  197. Instead of the "plt.exe" file there is another version of the compiler
  198. which uses the freeware extender PMODE. This is a "pltpmw.exe" file.
  199. This compiler demands less memory for the compilation and works faster
  200. then "plt.exe". Try to use it. If problems arise, use "plt.exe".
  201.  
  202.  
  203. Out of memory message
  204.  
  205. If you receive message "not enough memory for compilation", you have to
  206. either:
  207.  
  208.    - increase  a amount of free extended memory (for example, decrease
  209.      the "cash" of your hard disk), or
  210.    - decrease the value of the EXEMAK and OBJMAX parameters in the configuration
  211.      file, or
  212.    - switch on the virtual memory of DOS/4GW: To do this, include a line
  213.      "SET DOS4GW=1" into the your AUTOEXEC.BAT and use the compiler version
  214.      under the DOS/4GW extender.
  215.  
  216.  
  217. Configuration file
  218. ------------------
  219.  
  220. Before a compilation the compiler reads the settings from the special file -
  221. plt.cfg. It searches for one at the beginning of the current directory and
  222. then, if it doesn't find one, in the starting directory.
  223.  
  224. The configuration file "plt.cfg" contains the compilation parameters:
  225. one command per line. Empty line are possible. Comment line are started with
  226. the ';' symbol.
  227.  
  228. The following parameters can be used in the plt.cfg:
  229.  
  230.     toggle settings:
  231.  
  232.        w+       - turn on the puting of warning messages
  233.        r+       - turn on the range checking
  234.        q+       - turn on the overflow checking
  235.        i+       - turn on then automatic input/output result checking
  236.        t+       - typed pointers
  237.        x+       - extended syntax
  238.        v+       - strict var checking
  239.        optreg+  - turn on the register optimization
  240.        optfrm+  - turn on the stack frame optimization
  241.        opt+     - turn on all optimization (optreg+ & optfrm+)
  242.  
  243.     Default settings: w+, r+, q+, i+, t-, v+, x+, opt+.
  244.  
  245.     file path search specification:
  246.  
  247.        srcpath    <search_path> - specifies path for the source file search
  248.        objpath    <search_path> - specifies path for the object file (.FPD)
  249.                                   and STUBs search
  250.        objimppath <search_path> - specifies path for the OBJ import file
  251.                                   search by use of a $L directive
  252.  
  253.  
  254.        pseudo-devices SYS: and SRC: can be used in the path line:
  255.  
  256.          SYS: means the PLT compiler directory,
  257.          SRC: means the application program directory.
  258.  
  259.        defaults:  srcpath     src:;sys:
  260.                   objpath     src:;sys:
  261.                   objimppath  src:;sys:
  262.  
  263.  
  264.     buffer size specification:
  265.  
  266.        objmax <size>    - specifiies the size of the buffer for object
  267.                           modules (fpd-files). This parameter must be
  268.                           about one and a half times the size of the
  269.                           largest fpd-file from the project.
  270.  
  271.        exemax <size>    - specifies the maximum size of the executable
  272.                           module.
  273.  
  274.  
  275.        defaults:   objmax 333000
  276.                    exemax 256000
  277.  
  278.        These values are enough for ordinary work.  But if you receive
  279.        a message about overflowing of these buffers, you'll have to
  280.        increase them.  If you receive the message about unsufficient memory
  281.        for the compilation, you can try to decrease them.
  282.  
  283.     stack size specification:
  284.  
  285.        stack <stack_size> - specifies size of the application stack
  286.        default: 32000
  287.  
  288.     start up block (stub) name specification:
  289.  
  290.        stub  <stub_name>  - specifies the STUB name for the linker.
  291.                             default: DOS32.EXE
  292. +++0.30
  293.                             use the OBJPATH option to specify the seacrh path
  294.                             for the stub files
  295. ---0.30
  296.  
  297.  
  298.  
  299.     Symbol definition:
  300.  
  301.        def <symbol name>
  302.  
  303. +++0.30
  304.            The following symbols are predefined:
  305.                 __TMT__ :    always
  306.                 __DOS__ :    for DOS target
  307.             *   __OS2__ :    for all OS/2 targets
  308.             *   __DLL__ :    for .DLL targets
  309.             *   __PM__  :    for OS/2 Presentation manager targets
  310.             *   __FS__  :    for OS/2 Full screen targets
  311.             *           --   OS/2-hosted compiler only
  312. ---0.30
  313.  
  314.  
  315.     error message format specification:
  316.  
  317.  
  318.  
  319.        errmw+ - specifies the MetaWare Pascal format of the error message:
  320.  
  321.                    E "HELLO.PAS" L4/C16: type mismatch
  322.  
  323.  
  324.        errmw- - specifies BP-like format of the error message:
  325.  
  326.                    textcolor (lightred+'a');
  327.                               
  328.                    Error: HELLO.PAS (line 4, col 16): type mismatch
  329.  
  330.        This parameter allows use of the MultiEdit program as a shell
  331.        when the errmw+ parameter is set.
  332.  
  333.        The default is:  errmw-
  334.  
  335.      Output of the Dos32 logo specification:
  336.  
  337.        logo+  -  enables output of the Dos32 logo during the running of
  338.                  the emitted program.
  339.        logo-  -  disables output of the Dos32 logo during the running of
  340.                  the emitted program.
  341.  
  342.        The default is: logo+
  343.  
  344. Memory organization
  345. -------------------
  346.  
  347. The PLT compiler uses the Dos32 extender for a protected-mode program.
  348. The full distributive of Dos32 is in the DOS32 subdirectory.
  349. This distributive contains all information about program execution
  350. under the 32-bit mode.  Here some important issues are presented.
  351.  
  352. The segment registers are not used in the protected mode.  Instead all
  353. address space is separated on 4Kb pages starting from the zero address.
  354. Every page has a physical equivalent in the special table (the physical
  355. address might not be equal to the logical address).  In such a case the
  356. logical address 0 corresponds to the beginning of the program code.
  357. Therefore if you try to access the physical address (video memory and so
  358. on), you will not succeed.
  359.  
  360. Nevertheless, access to the physical addresses is possible, because
  361. the Dos32 extender reflects physical addresses into another set of special
  362. address pages.  To find the logical address from physical, you have to add
  363. the value of the special _zero varible from the SYSTEM unit to the physical
  364. address.
  365.  
  366. For example:
  367.  
  368.         procedure clr_video (filler: char);
  369.            var i: integer;
  370.         begin
  371.            for i := 0 to 80*25-1 do
  372.                mem [_zero+$B8000+i*2] := filler;
  373.         end;
  374.  
  375. This procedure fills the video memory of the VGA adapter with the
  376. filler symbol.
  377.  
  378. Note that the linear address $B8000 is used as the physical address - not
  379. the segment address $B800.
  380.  
  381. Some another special variables are described in the SYSTEM unit.
  382. The _psp variable contains the logical 32-bit address of the PSP of the
  383. program, and the _environ variable contains the environment address.
  384.  
  385. Although you can access the interrupt vectors by using this method,
  386. we do not suggest doing this.
  387.  
  388.  
  389.     Also keep in mind that MS-DOS interrupt handlers use memory
  390.     addresses in the 1st mb of physical memory while your program
  391.     and its data are loaded beyond the 1st mb. DOS32 intercepts
  392.     and correctly handles some, but not all, calls to MS-DOS.
  393.     Thus, if you are using Intr() or MsDos() calls, or call MS-DOS from
  394.     the assembler, you will need to modify the code.
  395.  
  396.     Additional details about this and related subjects can be found in
  397.     DOS32.DOC and API.DOC in subdirectory DOS32.
  398.  
  399.              Calling conventions
  400.              -------------------
  401.  
  402. Calling conventions match those in Borland Pascal with the following
  403. differences:
  404.  
  405.      all parameters use 4 bytes on the stack, or a multiple of 4 (BP:2)
  406.  
  407.      all procedures must preserve the contents of registers ebx, ecx, edx,
  408.      ds, and es!
  409.  
  410.      the direction bit should be cleared after the exit from a procedure,
  411.      if it has been modified by it.
  412.  
  413.  
  414.                 Language syntax of TMT Pascal/Fast:
  415.                 -----------------------------------
  416.  
  417. While the Language syntax of TMT Pascal/Fast is in general compatible with
  418. BP 7.0, there are some differences. Below is the list, divided into three
  419. groups: limitations, extensions, and incompatibilities.
  420.  
  421.  
  422.    1. Limitations:
  423.  
  424. Not implemented are MARK and RELEASE.
  425.  
  426. The INLINE() operator in implemented in a partial form:
  427.     INLINE (byte/byte/...);
  428. (No references to variables/constants are allowed).
  429.  
  430. Import of object modules does not support all 32bit object formats.
  431. We recommend using TASM which is fully supported, excepting
  432. usage of SEG addresses.
  433.  
  434.  
  435.    2. Extensions:
  436.  
  437. ADA-style comments are supported:  -- comment
  438. For example:
  439.  
  440.       space := ' ';  -- initialize filler char
  441.  
  442.  
  443.  
  444. Almost everywhere where Pascal's syntax allows a type identifier, we
  445. also allow a type descriptor. The compiler will produce a warning if you
  446. use this feature.
  447.  
  448. !!! Keep in mind that the rules of type equivalence stay in force.
  449.  
  450. Procedural values contain the address of the local environment (frame).
  451. Thus, any local procedures can be used in procedural values. Procedural
  452. declaration in the style
  453.  
  454.     procedure p (function f (a:real):real); ...
  455.  
  456. are also realized.
  457.  
  458.  
  459. The procedural value from a method of object can be obtained by
  460. selecting this method from some object value (not from a type). The
  461. parameters of this procedural value must match the parameters of the
  462. method.  The invocation of such a procedural value is an invocation of the
  463. corresponding method of the object.  The reference to the object is
  464. transferred through the base of the procedural value.
  465.  
  466. You can use only global procedural values to initialize a type constant.
  467.  
  468. !!! Procedural values may be used only while the environment where
  469. they were formed is still in existence.  Thus, for local procedures
  470. -- until the exit from the block, in which they are described; for
  471. methods -- while the underlying object still exists.
  472.  
  473. see also "incompatibilities."
  474.  
  475. With TMT Pascal you can use any statement as a procedure body,
  476. except for the assignment and the procedure calls.
  477.  
  478. The RESULT variable in the body of such functions denotes the variable
  479. that contains the return value.  The RESULT is of the function return type
  480. and may be used as a variable without any restrictions.
  481.  
  482. With TMT Pascal you can enter the procedure body directly as a procedure
  483. parameter.  The procedure or function header (if not specified) takes the
  484. procedural parameter type.  If the procedure header is specified, the
  485. procedure name is omitted.  Example:
  486.  
  487. function integral (function f (a:real):real; low, high, step: real): real;
  488. begin ... end;
  489.  
  490.     ...
  491.     writeln (integral (
  492.          function (x:real):real; begin result := sqrt (x) end,
  493.     0, 10, 0.1));
  494.  
  495.     writeln (integral (begin result := sqrt (a) end, 0, 10, 0.1));
  496.  
  497.     writeln (integral (
  498.          function;        -- function keyword needed
  499.              var x: real; -- for local declaration
  500.          begin x := sqrt (a); result := x end,
  501.     0, 10, 0.1));
  502.  
  503.     writeln (integral (
  504.          declare;         -- other way
  505.              var x: real; -- for local variable declaration
  506.          begin x := sqrt (a); result := x end,
  507.     0, 10, 0.1));
  508.  
  509. TMT Pascal allows exit from a local procedure to the one that contains it.
  510. This feature is listed in the Pascal's ANSI standard but not realized in
  511. BP. Together with procedural values, this is very useful for error handling:
  512.  
  513. Program test;
  514.     Var on_eof: procedure;
  515.     Function read_char: char;
  516.         Var c: char;
  517.     Begin
  518.         If Eof (Input) Then on_eof;
  519.         read (c);
  520.         read_char := c;
  521.     End;
  522.  
  523.     Procedure p;
  524.         Label eof_reached;
  525.         Procedure go_eof; Begin goto eof_reached; End;
  526.     Begin
  527.         on_eof := go_eof;
  528.         While True Do Write (read_char);
  529.     Eof_reached:
  530.         Writeln ('*** EOF ***');
  531.         on_eof := NIL;
  532.     End;
  533.  
  534. Begin
  535.     p;
  536. End.
  537.  
  538. Restriction: BREAK and CONTINUE operators cannot be used for exit
  539. from a procedure. Use GOTO instead.
  540.  
  541. Example:
  542.  
  543.         for i := 1 to 10 do
  544.             writeln (integral (  -- function integral from previous example
  545.                 if a < 0 then break else result := sqrt (a), -- incorrect
  546.             i, i + 1, 0.01));
  547.  
  548.         declare
  549.             label L;
  550.         begin
  551.             for i := 1 to 10 do
  552.                 writeln (integral (
  553.                     if a < 0 then goto L else result := sqrt (a), -- correct
  554.                 i, i + 1, 0.01));
  555.         L: end;
  556.  
  557. Functions may return any values of any type, including structures and arrays.
  558.  
  559.  
  560. The new operator DECLARE
  561.  
  562.    DECLARE
  563.        <declaration part>
  564.    BEGIN
  565.        <statement list>
  566.    END
  567.  
  568.  
  569. allows one to describe local variables and procedures anywhere in the
  570. program.  Use of "DECLARE" leads to more readable programs and conserves
  571. the stack space.
  572.  
  573. Functions length, chr, ord may be used as variables. For example:
  574.  
  575.          chr (i) := ' ';   is equivalent to   i := ord (' ');
  576.          ord (c) := 255;   is equivalent to   c := chr (255);
  577.          length (s) := 10; is equivalent to   s [0] := chr (10);
  578.  
  579.  
  580. The main program may contain "interface" and "implementation".
  581. This allows access to the variables of the main program from other
  582. modules:
  583.  
  584.     Program test;
  585.     Interface
  586.        Var global: Integer;
  587.     Implementation
  588.        Uses Unit_test;
  589.     Begin
  590.        Unit_test.write;
  591.     End.
  592.  
  593.     Unit Unit_test;
  594.     Interface
  595.         Procedure Write_global;
  596.     Implementation
  597.         Uses test;
  598.         Procedure Write_global;
  599.         Begin
  600.             Write (test.global);
  601.         End;
  602.     End.
  603.  
  604.  
  605. !!! Here the name of the file that contains the text of the main program
  606. must be identical with the name that follows the keyword "program".
  607.  
  608. New type: DWORD - an unsigned 32-bit integer (same as unsigned long in C).
  609. It can be useful in many cases, but keep in mind that during arithmetic
  610. operations between DWORD's and LONGINT's both arguments are casted to
  611. LONGINT's. This may cause an error.
  612.  
  613. ABSOLUTE may refer to fields of records and objects.  Also, the
  614. address of a global record/object field can be used within the initialization
  615. of typed constants.  Furthermore one can use recursive initialization:
  616.  
  617. type rec = record
  618.                next: ^rec;
  619.                buffer: array [1..10] of char;
  620.                buf_adr: pointer;
  621.            end;
  622.  
  623. const cyclic: rec = (next: @cyclic; buf_adr: @cyclic.buffer);
  624.  
  625. In initialization of structures and objects the fields may go in
  626. an arbitrary order. If a field is not listed, it is zeroed up.
  627.  
  628. The syntax of the STR operator has been extended:
  629.  
  630.     STR (value[:width[:precision]], ..., dest);
  631.  
  632. Here STR (name:2, ':', ext:3, dst); is equivalent to
  633.  
  634.         STR (name:2, temp1);
  635.         STR (':',    temp2);
  636.         STR (ext:3,  temp3);
  637.         dst := temp1 + temp2 + temp3;
  638.  
  639. Negative field widths in WRITE, WRITELN, and STR left align the value within
  640. its field.
  641.  
  642. !!! The Strings unit contains additional functions which may be more
  643.     convenient than the STR operator.
  644.  
  645. +++0.30
  646.  
  647.      Multidimensional open arrays:
  648.  
  649. You can now use in procedure parameters and functions descriptions
  650. "array (<dim>) of <type>", where <dim> is a positive integer constant, defining
  651. the number of dimensions, ánd <type> is the type of the array elements.
  652. To determine the upper bounds of the array, use the "high (array)" function.
  653. It returns a vector of longints ("array [0..<dim>-1] of longint") containing
  654. the upper bounds. The lower bounds are always set to 0. The vector of the lower
  655. bounds can be obtained with a similar function "low".
  656.  
  657. Example:
  658.  
  659.  
  660. procedure print_vector (v: array (1) of double);
  661. var i: integer;
  662. begin
  663.     for i := 0 to high (v) [0] do write (v [i]:10:6, ' ');
  664.     writeln;
  665. end;
  666.  
  667. procedure print_matrix (m: array (2) of double);
  668. var i: integer;
  669. begin
  670.     for i := 0 to high (m) [0] do print_vector (m [i]);
  671.     writeln;
  672. end;
  673.  
  674. const a: array [1..3, 1..3] of double = ((1,0,2),(2,1,0),(1,2,1));
  675.  
  676. begin
  677.     print_matrix (a);
  678. end.
  679.  
  680. You can find an example program for solving a system of linear equations in
  681. the directory "EXAMPLES\LIN_EQ".
  682.  
  683. ---0.30
  684.  
  685. +++0.40
  686.          NEW!!!: User defined operations.
  687.  
  688. TMT Pascal allows redefining of the standard operations on predefined types and ¿
  689. overloading of these operationg for new types. For this, we use the construction
  690.  
  691.     OVERLOAD:
  692.  
  693. The syntax is:
  694.  
  695.     OVERLOAD op_sign = qualified procedure identifier;
  696.  
  697. Where the op_sign is one of the standard operation symbols:
  698.  
  699.      + - / * = <> < > <= >= AND OR XOR SHL SHR MOD DIV IN NOT
  700.      +:=   -:=   *:=   /:=
  701.  
  702. When a re-defined operation is used, TMT Pascal uses the last definition that
  703. could be applied toward operants of given types. For example, this fragment
  704.  
  705.     FUNCTION add2_rr (a, b:    REAL):    REAL; result := (a + b) * 2;
  706.     FUNCTION add2_ii (a, b: INTEGER): INTEGER; result := (a + b) * 2;
  707.  
  708.     OVERLOAD + = add_rr;
  709.     OVERLOAD + = add_ii;
  710.  
  711. redefines the "+" operation. Notice that the order of OVERLOAD's is important.
  712. The reverse order
  713.  
  714.     OVERLOAD + = add_ii;
  715.     OVERLOAD + = add_rr;
  716.  
  717. will cause "add_rr" used *always* since integers can always be cast into
  718. reals.
  719.  
  720. In the SOURCES subdirectory you can find the source of the COMP module which
  721. realizes the complex numbers and defines the operations on them.
  722.  
  723. Operations +:=, -:=, *:= and /:= have the lowest precedence (lower, than the comparison
  724. operations) and are right-associative. The operations "+:=" and "-:=" are
  725. predefined for all integer and real types; the operations "*:=" and "/:="
  726. are predefined for all real types, with the obvious meaning.
  727.  
  728. See also description of Strings unit.
  729.  
  730.  
  731.      NEW: Iterated typed array constats:
  732.  
  733.      you can use the notation "..." in the array initialization.
  734. The ellipses should be the last element in the initialization list. If
  735. used, the remaining elements of the array are filled up with the
  736. last given value that preceded the ellipses. Ellipses cannot be the first
  737. element of the initialization list.
  738.  
  739. Example:
  740.  
  741. const a: array [1..10, 1..10] of integer = (
  742.     (1,...), (2,...), (3,...), (4, 5, 6, ...), (0, ...), ...
  743. );
  744.  
  745. fills up the 10 by 10 array as follows:
  746.  
  747.         1 1 1 1 1 1 1 1 1 1
  748.         2 2 2 2 2 2 2 2 2 2
  749.         3 3 3 3 3 3 3 3 3 3
  750.         4 5 6 6 6 6 6 6 6 6
  751.         0 0 0 0 0 0 0 0 0 0
  752.         0 0 0 0 0 0 0 0 0 0
  753.         0 0 0 0 0 0 0 0 0 0
  754.         0 0 0 0 0 0 0 0 0 0
  755.         0 0 0 0 0 0 0 0 0 0
  756.         0 0 0 0 0 0 0 0 0 0
  757.  
  758.  
  759. ---0.40
  760.  
  761.     3. Incompatibilities:
  762.  
  763. Procedural values is 8-byte long and has the following format:
  764.  
  765. 0   +-----------------------+
  766.     | The entry point       |
  767. 4   +-----------------------+
  768.     | The local environment |
  769. 8   +-----------------------+
  770.  
  771. However, a pointer to a procedure is only 4-byte long and contain only the
  772. address of the entry point. The @ operator verifies that the procedure is
  773. global. Otherwise a range error is generated.
  774.  
  775. Furthermore, the stack frame structure and parameter passing conventions
  776. differ from those in BP.
  777.  
  778. Thus the approach used in TVision and CLassLib for writing iterators
  779. cannot be used. However, we offer this correct and reliable (and more
  780. standard) way:
  781.  
  782.      Type list = object
  783.                      next: ^list;
  784.                      procedure for_all (procedure body (var v));
  785.                  end;
  786.  
  787.      Procedure list.for_all;
  788.          Var p: ^list;
  789.      Begin
  790.          p := @self;
  791.          repeat
  792.              body (p);
  793.              p := p^.next;
  794.          end;
  795.      End;
  796.  
  797.      ...
  798.  
  799.      Type int_list = object (list)
  800.                          value: integer;
  801.                          function first_positive: ^int_list;
  802.                      end;
  803.  
  804.      Function int_list.first_positive;
  805.          Label OK;
  806.          Var res: ^int_list;
  807.          Procedure do_item (var v);
  808.          Begin
  809.              If int_list (v).value > 0 Then
  810.              Begin
  811.                  res := @v;
  812.                  GoTo OK;
  813.              End
  814.          End;
  815.      Begin
  816.          res := nil;
  817.          for_all (do_item);
  818.      OK:
  819.          first_positive := res;
  820.      End;
  821.  
  822.      ...
  823.  
  824.  
  825.  
  826. Since in the flat model there are no segments, SEG() always returns 0,
  827. while PTR() ignores its first parameter.
  828.  
  829. !!! Be careful with these functions: in practice, any use of PTR() or SEG()
  830.     in your program may require a program modification.
  831.  
  832. Pseudo-array Mem and MemW are used as follows:
  833.  
  834.     i := MemW [<linear address>]
  835.  
  836. Note that the segment is not given. Furthermore, the pseudo-arrays
  837. MemD and PortD of type DWORD are available.
  838.  
  839. See "Memory organization" for more details.
  840.  
  841.  
  842.            Built-in assembler
  843.            ------------------
  844.  
  845. The built-in assembler of TMT Pascal Lite is 32-bit.  It is compatible
  846. with the BP's built-in assembler with the following differences:
  847.  
  848. Since the program created by the Pascal Lite is executed in the flat
  849. model, the far call and jump commands as well as the @Code and @Data symbols
  850. are not implemented.
  851.  
  852. The ret command:
  853.  
  854. The ret command without arguments is considered as a ret <parameter block
  855. size> command.  If you need to write the ret command without size you should
  856. set 0 explicitly:
  857.  
  858.       ret 0
  859.  
  860. Code-procedure
  861.  
  862. Besides the assembler-routine you can use the code-routine.  It has the
  863. following differences: the compiler doesn't emit the frame command on
  864. enter and return from the routine (including the ret command), and the local
  865. parameters are based on ESP on the moment of entry.
  866.  
  867. Example:
  868.  
  869.     function hi (n: word); code;
  870.     asm
  871.         mov al, byte ptr [n+1]
  872.         ret
  873.     end;
  874.  
  875.  
  876.            Supplied units:
  877.            ---------------
  878.  
  879. The following units are included:
  880.      SYSTEM.FPD - standard library functions
  881.         DOS.FPD - MS-DOS interface.
  882.                   Corresponds to the DOS unit of BP.
  883.         CRT.FPD - Text mode screen interface.
  884.                   Corresponds to the CRT unit of BP.
  885.       USE32.FPD - Define type Integer as 32-bit etc.
  886.    ERRCODES.FPD - Run-time error codes.
  887.       DEBUG.FPD - Some debugging code.
  888.     STRINGS.FPD - String handling functions.
  889.                   Corresponds to the STRINGS unit of BP.
  890.  
  891. Besides these modules, the distribution includes DOSCALL.FPD and ARG.FPD,
  892. which are needed for linkage. These modules should not be called by the user.
  893.  
  894.  
  895.            The DOS Unit
  896.            ------------
  897.  
  898. This corresponds to the DOS unit of BP.
  899.  
  900. Differences:
  901.  
  902.  Type FarPointer = record ofs: pointer; seg: word end;
  903.  
  904.  The function GetIntVec has the following syntax:
  905.      procedure GetIntVec (IntNo: Byte; var Vector: FarPointer);
  906.  
  907.  and not
  908.      procedure GetIntVec (IntNo: Byte; var Vector: Pointer);
  909.  
  910.  New procedures:
  911.  
  912.      procedure GetIntVecFar (IntNo: Byte;   var Vector: FarPointer);
  913.      procedure SetIntVecFar (IntNo: Byte; const Vector: FarPointer);
  914.  
  915.     GetIntVec is equivalent to GetIntVecFar().
  916.  
  917.     SetIntVec is equivalent to SetIntVecFar(), but uses in the segmented
  918.       address the current CS.
  919.  
  920. A header of an interrupt procedure should have the following form:
  921.  
  922. procedure handler (
  923.     eip, eax, ecx, edx, ebx, esp, ebp, esi, edi: dword;
  924.     gs, fs, es: word
  925. ); interrupt;
  926.  
  927.  
  928. The Registers type has this structure:
  929.  
  930.  type Registers =
  931.     record
  932.         edi, esi, ebp, _res : dword;
  933.     case boolean of
  934.         true:  (ebx, edx, ecx, eax: dword;
  935.                 flags, es, ds, fs, gs, ip, cs, sp, ss: word);
  936.         false: (bl, bh, b1, b2, dl, dh, d1, d2, cl, ch, c1, c2, al, ah: byte);
  937.     end;
  938.  
  939.  
  940.  
  941. !!! When using Intr() and MsDos(), keep in mind that the DOS
  942.     interrupt handlers can deal only with the addresses from the 1st
  943.     megabyte of memory.
  944.  
  945.  
  946.            The CRT unit
  947.            ------------
  948.  
  949. Corresponds to the CRT unit of BP.
  950.  
  951.            The USE32 unit
  952.            ------------
  953.  
  954. Contains redefinitions of integer types for 32-bit computing as follow:
  955.  
  956.     type
  957.       SmallInt   = System.Integer;
  958.       SmallWord  = System.Word;
  959.       Integer    = System.Longint;
  960.       Word       = System.Longint;
  961.  
  962.     const
  963.       MaxInt     = high(longint);
  964.  
  965.     type
  966.       PByte      = ^Byte;
  967.       PWord      = ^Word;
  968.       PLongint   = ^Longint;
  969.       PSmallInt  = ^SmallInt;
  970.       PSmallWord = ^SmallWord;
  971.  
  972.  
  973.            The ERRCODES unit
  974.            -----------------
  975.  
  976. Contains constants for error codes, given by RUNERROR(),
  977. and the error_msg(code: Word): String, function that decyphers the error code.
  978.  
  979.  
  980.            The DEBUG unit
  981.            --------------
  982.  
  983. This module prints out the error code and the call stack in case of a
  984. run-time error. The stack is printed as follows:
  985.  
  986. RunError #201 (range check error)
  987. Calls stack:
  988. SYSTEM.BOUND_ERROR [chk_fun.inp(21) at 0000000A]
  989. TEST.ASSN [TEST.PAS(61) at 00000015]
  990. TEST.TEST [TEST.PAS(82) at 0000001D]
  991.  
  992. To use DEBUG, simply list it in the USES clause of the main program.
  993.  
  994. +++0.33
  995.  
  996. Using the debug UNIT increases the .exe module size
  997.  
  998. !!! Note: a call of a procedure with a NULL address is currently diagnosed as
  999.     an arithmetic overflow, or (under the PMODE extender) caused a GP Fault or
  1000.     other traps
  1001. ---0.33
  1002.  
  1003.            The STRINGS unit
  1004.            ----------------
  1005.  
  1006. Corresponds to the STRING unit of BP.
  1007. Also contains additional functions:
  1008.  
  1009. Function hex (n: DWord   ): String [12];
  1010.     -- prints the argument in hex.
  1011.  
  1012. Function whl (n: LongInt ): String [12];
  1013.     -- prints the argument as a signed integer.
  1014.  
  1015. Function uns (n: DWord   ): String [12];
  1016.     -- prints the argument as an unsigned integer.
  1017.  
  1018. Function fix (x: Extended; pr: LongInt): String [15];
  1019.     -- prints a real with fixed point. pr is the number of digits after the
  1020.        decimal point.
  1021.  
  1022. Function align (str: String; width: LongInt): String;
  1023.     -- pads the argument up to width with spaces.
  1024.        spaces are on the right if width>0, and on the left otherwise.
  1025.  
  1026. +++0.40
  1027.       Additional functions defined in STRINGS:
  1028.  
  1029.       FUNCTION Dup_SI (CONST s: STRING; n: INTEGER): STRING;
  1030.           - copies the string "n" times
  1031.  
  1032.       FUNCTION Dup_æI (ß: CHAR; n: INTEGER): STRING;
  1033.           - creates the string by repeating character "c" "n" times.
  1034.  
  1035.       These functions are defined as operations:
  1036.  
  1037.             OVERLOAD * = Dup_SI;
  1038.             OVERLOAD * = Dup_CI;
  1039.  
  1040.       For example, you can write 'ab'*4 instead of 'abababab'.
  1041.  
  1042.       FUNCTION AppendStr (VAR dst: STRING; CONST src: STRING);
  1043.           - appends "src" at the end of "dst"
  1044.  
  1045.       FUNCTION AppendStrC (VAR dst: STRING; src: CHAR);
  1046.           - appends character "src" to the end of string "dst"
  1047.  
  1048.       These functions are defined as operations:
  1049.  
  1050.             OVERLOAD +:= = AppendStr;
  1051.             OVERLOAD +:= = AppendStrC;
  1052. ---0.40
  1053.  
  1054.  
  1055. +++0.37
  1056.            The MOUSE unit
  1057.            --------------
  1058.  
  1059. The MOUSE unit gives a Pascal program the access to the main
  1060. mouse-support functions:
  1061.         * Determining presense/absense of the mouse
  1062.         * Mouse cursor positioning
  1063.         * Getting information about the position and the button states
  1064.         * Installing a mouse-driven Pascal interrupt handler.
  1065.  
  1066. Variables:
  1067.  
  1068. var ButtonCount:  Word;
  1069.     During initilaization has value 0; after a call to InitMouse()
  1070.     this variable becomes either 0 (no mouse), or the number of
  1071.     available buttons (2 or 3).
  1072.  
  1073. Procedures & Functions:
  1074.  
  1075. Procedure InitMouse;
  1076.  
  1077.      Does the following:
  1078.      - Allocates a 4K stack for the user's mouse interrupt-driven
  1079.        procedure.
  1080.      - Determines the presence or absence of the mouse and sets the
  1081.        ButtonCount variable.
  1082.      - If mouse is present:
  1083.           - Enables the mouse cursor (calls ShowMouse)
  1084.           - Positions the cursor to the upper-left screen corner;
  1085.           - Reserves the callback address for the users' interrupt-driven
  1086.             mouse procedure (regardless of whether it will get installed or
  1087.             not).
  1088.  
  1089. Procedure ShowMouse;
  1090.  
  1091.      When mouse is present, makes its cursor visible (INT 33 01).
  1092.  
  1093. Procedure HideMouse;
  1094.  
  1095.      When mouse is present, makes its cursor invisible (INT 33 02).
  1096.  
  1097. Procedure SetMousePos (X, Y: Integer);
  1098.  
  1099.      Positions the Mouse Cursor to the point (X,Y).
  1100.      Both coordinates start with 0.
  1101.  
  1102. Procedure GetMouseInfo (var ButtonMask:Word;  var X:Word; var Y:Word);
  1103.  
  1104.      Returns information about the position of the mouse cursor (X,Y)
  1105.      and the pressed buttons (ButtonMask).
  1106.  
  1107. Procedure SetMouseHandler (Mask:Word;
  1108.                                 procedure Hnd (Mask,
  1109.                                                Buttons,
  1110.                                                X,Y,
  1111.                                                MovX,MovY:Word;))
  1112.  
  1113.      Installs a Pascal interrupt-driven user's mouse handler (Hnd).
  1114.      The Mask parameter defines the classes of the events that call
  1115.      the handler; its format corresponds to the function INT 33 0C.
  1116.      When Hnd is called the Mask parameter contains the mask with the
  1117.      event type that occurred; Buttons contain the mask of the currently
  1118.      pressed buttons; X and Y contain the cursor's absolute position, and
  1119.      MovX and MovY contain the relative (signed) change of the last cursor
  1120.      position [negative numbers mean left or down; positive mean
  1121.      right or up]. These values are given in mouse position units; to
  1122.      convert to symbols, they need to be divided by 8.
  1123.  
  1124.      Using SetMouseHandler you can install several handlers with different
  1125.      masks without having to clear previous handlers.
  1126.  
  1127. Procedure ClearMouseHandler;
  1128.  
  1129.      Removes the user's mouse interrupt handler.
  1130.  
  1131. Procedure DoneMouse;
  1132.  
  1133.      Does the following:
  1134.  
  1135.         - removes (hides) the mouse cursor;
  1136.         - frees the callback address for the mouse interrupt handler;
  1137.         - frees the stack for the mouse interrupt handlers;
  1138.         - resets ButtonCount to 0.
  1139. ---0.37
  1140.  
  1141. +++0.33
  1142. *******************VERSION 0.33 CHANGES*******************************
  1143.  
  1144. This version of the compiler uses a new DOS extender (based on the
  1145. PMODE package). It emulates the DOS32 functions that are necessary
  1146. for run-time support of Pascal programs, which allows to use both the
  1147. new extender as well as DOS32. The full list of the DOS32 functions, which are
  1148. supported by the new extender is given at the end of this document
  1149. The main difference of the new extender is that the 1st MB of the physical
  1150. RAM is mapped to the 1st MB of the virtual memory while the program is
  1151. loaded into higher addressed. This corresponds to the value _zero = 0.
  1152. Thus, with the new extender it is possible to use absolute memory addressing:
  1153.  
  1154.    var vmem: array [1..25, 1..80] of word absolute $b8000;
  1155.  
  1156. Because of this we could now implement some other BP7.0 constructs:
  1157.  
  1158.     mem [seg:offs]
  1159.     var x:type absolute seg:offs
  1160.  
  1161. Here the effective address is computed as seg*16+offs.
  1162. The Ptr (seg, offs) function works similarly. The seg(v)
  1163. function still always returns 0.
  1164.  
  1165. These new functions should substantially simplify the conversion of the
  1166. programs that use absolute addressing.
  1167.  
  1168. An example of using these functions can be found in file
  1169. EXAMPLES\FLAME\FLAME1.PAS
  1170.  
  1171. By default PLT uses the new extender (stub passtub.exe);
  1172. the old one (DOS32) can be used by specifying the
  1173. command line parameter -stub:dos32.exe or adding the line
  1174.         stub dos32.exe
  1175. in the configuration file.
  1176.  
  1177. The support for the DOS32 extender is likely to be entirely removed
  1178. in the next version of PLT. Unless you discover some specific problems
  1179. with the new extender (please report them if you do!), you should not
  1180. use the DOS32 stub loader.
  1181.  
  1182. ---------
  1183.  
  1184. The following DOS32 functions are supported by the new extender:
  1185.  
  1186. subfunctions of INT 31h:
  1187.    EE40h
  1188.    EE42h
  1189.  
  1190. subfunctions of INT 21h:
  1191.   39h, 3Ah, 3Bh, 3Ch, 3Dh, 3Fh, 40h
  1192.   41h, 42h, 4300h, 4301h, 47h, 4Bh, 4Eh, 4Fh, 56h, 5Ah, 5Bh
  1193.  
  1194. **********************************************************************
  1195. ---0.33
  1196.  
  1197. +++0.37
  1198. *******************VERSION 0.37 CHANGES*******************************
  1199. New unit: MOUSE.
  1200.  
  1201. No syntax changes; numerous errors in the PMODE-based extender and
  1202. the compiler are corrected.
  1203. **********************************************************************
  1204. ---0.37
  1205.  
  1206. +++0.40
  1207. *******************VERSION 0.40 CHANGES*******************************
  1208. User defined operators added
  1209. Iterated typed array constants added
  1210. Extra Strings function added
  1211. Many bugs fixed, code size of PMode extender reduced to 11KB.
  1212. **********************************************************************
  1213. ---0.40
  1214. +++0.41
  1215. *******************VERSION 0.41 CHANGES*******************************
  1216.  
  1217. New variable initialization within their declaration:
  1218.  
  1219. TMT Pascal now allows variable declarations like:
  1220.  
  1221.    Var i,j: integer := n*n;
  1222.          k: integer := i+j;
  1223.  
  1224. Expressions are computed and assigned whenever the block is entered.
  1225. When more than one variable is initialized within the same expression,
  1226. the expression is computed only once.
  1227.  
  1228. Within the expressions you can use all the variables declared in the
  1229. outside blocks, as well as the variables in the current block which
  1230. declarations precede the expression.
  1231.  
  1232. ALSO: Added directives
  1233.  
  1234.    ALIGN 2
  1235.    ALIGN 4
  1236.  
  1237.   in built-in assembler. The padding is done with the $90 byte (NOP).
  1238.  
  1239. **********************************************************************
  1240. ---0.41
  1241.  
  1242. +++1.00
  1243. *******************VERSION 1.00 CHANGES*******************************
  1244.  
  1245. A number of bugs fixed; the quality of code generated improved;
  1246. full on-line documentation added.
  1247. ---1.00
  1248.  
  1249.  
  1250.                    Possible problems during usage
  1251.                    ------------------------------
  1252.  
  1253.     Programs, generated by TMT Pascal, abend under OS/2. Correction:
  1254.       - ensure that in "memory settings" EMS_MEMORY_LIMIT is not equal to 0.
  1255.  
  1256. +++0.33
  1257.                    Run-time errors codes
  1258.                    -------- ------ -----
  1259.  
  1260.   1    Invalid function number
  1261.   2    File not found
  1262.   3    Path not found
  1263.   4    Too many open files
  1264.   5    File access denied
  1265.   6    Invalid file handle
  1266.  12    Invalid file access_code
  1267.  15    Invalid drive number
  1268.  16    Cannot remove current directory
  1269.  17    Cannot rename across drives
  1270.  18    No more files
  1271. 100    Disk read error
  1272. 101    Disk write error
  1273. 102    File not assigned
  1274. 103    File not open
  1275. 104    File not open for input
  1276. 105    File not open for output
  1277. 106    Invalid numeric format
  1278. 150    Disk is write protected
  1279. 151    Bad drive request struct length
  1280. 152    Drive not ready
  1281. 154    CRC error in data
  1282. 156    Disk seek error
  1283. 157    Unknown media type
  1284. 158    Sector not found
  1285. 159    Printer out of paper
  1286. 160    Device write fault
  1287. 161    Device read fault
  1288. 162    Hardware failure
  1289. 200    Division by zero
  1290. 201    Range check error
  1291. 202    Stack overflow error
  1292. 203    Heap overflow error
  1293. 204    Invalid pointer operation
  1294. 205    Floating point overflow
  1295. 206    Floating point underflow
  1296. 207    Invalid floating point operation
  1297. 208    Overlay manager not installed
  1298. 209    Overlay file read error
  1299. 210    Object not initialized
  1300. 211    Call to abstract method
  1301. 212    Stream registration error
  1302. 213    Collection index_out of range
  1303. 214    Collection overflow error
  1304. 215    Arithmetic overflow error
  1305. 216    General protection fault
  1306. 217    Invalid operation_code
  1307. 300    File io error
  1308. 301    Nonmatched array bounds
  1309. 302    Non local procedure pointer
  1310. 303    Procedure pointer out of scope
  1311. 304    Function not implemented
  1312. 305    Breakpoint error
  1313. 306    Break by ctrl/C
  1314. 307    Break by ctrl break
  1315. 308    Break by other process
  1316. 309    No floating point coprocessor
  1317.  
  1318. ---0.33
  1319.  
  1320.